Zerocat Chipflasher: kick

README

How to Build kick, the First Firmware

Configure: Board Version

To configure kick for board v2 (e.g. Chipflasher v2), the default, type:

    [env]$ make -C ../../firmware1/src config-BOARD_V2

To configure kick for board v1 (e.g. Chipflasher ‘board-edition-1’), type:

    [env]$ make -C ../../firmware1/src config-BOARD_V1

Configure: Baudrate

The host utility and the firmware use a serial connection for their communication. The speed of that connection is specified as baudrate.

The default baudrate is: 115200

Baudrate configuration is retrieved from file ../../firmware1/start/board.cfg, which in turn is managed via ../../firmware1/start/Makefile.

Compile

To build kick, type:

    [env]$ make -C ../../firmware1/src kick

Help

To get a full list of available targets, type:

    [env]$ make -C ../../firmware1/src help

Clean Up

To clean files and folders, type:

    [env]$ make -C ../../firmware1/src clean

How to Upload kick

To upload kick to onboard, free-design RAM, type:

    [env]$ make -C ../../firmware1/start kick-ram

To upload kick to onboard, proprietary-design EEPROM, type:

    [env]$ make -C ../../firmware1/start kick-eeprom

Help

To get a full list of available targets, type:

    [env]$ make -C ../../firmware1/start help

Configuration Registers

The chipflasher not only accesses the main memory array of SPI chips, it also gives you full control over the chips’ configuration registers:

In case of chips made by Macronix, it even provides access to the lock bits of the security register, as well as to the secured, one-time-programmable region of these chips (typically 64 bytes in size):

Clean up and lock the region, before someone else will do it!

Clean-up Examples:

• In case the lock bit is set, there is no clean-up you can do.
• In case the SOTP region has not been written, just lock it.
• In case the SOTP region has been written but is not locked, write zeros and lock it.
• In case the SOTP region cannot be locked, as no lock bit is available (i.e. commercial grade chips), just write zeros to the SOTP region.

How to Use Chipflasher ‘board-edition-1’

Thank you for trying kick, the first firmware, with Zerocat Chipflasher ‘board-edition-1’!

Zerocat Chipflasher is your free-design hardware tool for flashing free firmware to BIOS chips. See #../../doc/targets.md for supported chips and targets.

Hardware Features

• Parallax Propeller P8X32A free-design hardware controller

  The core of the chipflasher...

  • Talks to the host via RS232 serial data lines
  • Runs the SPI bus with 2.5MHz
  • Provides free-design hardware RAM that is used to hold the firmware

• Onboard EEPROM (non-free chip design)

  May be used optionally for long-term firmware storage.

• Power Switch, Power Status LED and SPI Power LED

  The switch gives a good tactile feedback when powering the flasher and the LEDs clearly reflect the power status of the onboard regulators.

• Software status LEDs

  • yellow: No SPI-Plug is attached.
  • orange: Controller’s RST Pin is muted and allows starting from RAM.
  • green: Reflects the menu status. The LED is continuously on if no input is requested, otherwise a pulse train is emitted according to the current input level.

• SPI-Bus Status LED (red)

  When powered, the SPI-Bus is in use and the SPI chip is powered. Do not disconnect the SPI-Plug or test-clip if this LED is active!

• Variable pull-up, allows to drive the SPI-CE#-line with a dedicated strength.

  Use a screw-driver clockwise to adjust the pull-up to its highest value, thus resulting in the weakest driver strength. Then turn counter-clockwise until access to your target is reliable.

• USB powered, typical load: 1.000mA maximum

  • In order to delimit power dissipation, an input voltage of 5VDC is recommended. Do not use any input voltages above 6VDC.

  • The typical load current won't exceed 1.000mA. Note the chipflasher board uses a Polyfuse which will shut off the board if drawing currents in excess of 1.500mA.

• Data connection: RS232, pinheader-5x2

• SPI connection: +3.3VDC/GND, pinheader-9x1

• Handy dimensions (lenght x width x height) approx. 100 x 80 x 80mm

• Pinout info for each connector right on the chipflasher’s front panel.

• Accessories

  • Y-USB-Power-Cable Plug-A to Plug-A
  • RS232-cable with SUBD-9 connector
  • universal SPI-Cable with four pinheader connectors
  • 8Pin-DIL Socket for non-soldered BIOS chips

Recommended Add-Ons in Case of Purchase

• Standard add-ons

  • secure package with ESD protection
  • CD with chipflasher’s source code
  • SOIC16 clip, to be used with chips in situ
  • Sn99.3 Cu0.7 leadfree soldering
  • product information paper

• Options upon request

  • SOIC8 clip, to be used with chips in situ
  • Solder Kit with pinheader and flying wires for WSON chips
  • external USB Power Adapter 5V@1000mA
  • Host computer with RS232 port, running with coreboot firmware

Typical Setup

The typical setup requires a host that has an RS232 serial port available, as the chipflasher board doesn't provide its USB port for data, it is used for power only.

We recommend to drive the flasher with a librebooted or corebooted 64bit X60 ThinkPad. These machines can be flashed with the flashrom user space utility. A serial port is part of their docking station.

A typical setup looks like this:

1. Computer with RS232 port, i.e.:

   • ThinkPad X60 with Docking Station and coreboot/libreboot firmware
   • Intel D945GCLF board with coreboot, no blobs required
   • other blobless desktop boards like GA-945GCM-S2L and GA-G41M-ES2L

2. The Zerocat Chipflasher

3. supported SPI flash chip, a single one or one soldered in place on its system board (section #../../doc/targets.md)

4. external USB-Power-Adapter (5V @ 1000mA) or at least two USB-ports from the computer.

You will use three cables for connection:

• the USB cable for 5V power supply of the chipflasher board

  (If you use two USB ports for power, use an Y-USB cable.)

• RS232 data cable for data transfer between host and chipflasher

• SPI-cable (8 wires, length about 20cm) with 8pin-DIL-socket or SMD-test-clip to attach the target SPI flash chip

Setup with External USB Power Adapter

    +------------+                +-------------+           +·············+
    | Host, i.e. |                | Zerocat     |           +---------+   :
    |  X60 +     |                | Chipflasher |---+3.3V-->| SPI     |   :
    |  Docking   |<--RS232-data-->|             |<---SPI--->|  Chip   |   :
    |            |                | firmware:   |           +---------+   :
    | software:  |      +--+5V--->|  `kick'     |           :             :
    | `connect'  |      |         +-------------+           : Systemboard :
    +------------+      |                                   : without     :
                    +--------------------+                  : Battery     :
                    | External USB Power |                  : nor Power   :
                    |  5V @ 1000mA       |                  +·············+
                    +--------------------+

Setup with Non-standard Y-USB-Cable

    +------------+                +-------------+           +·············+
    | Host, i.e. |                | Zerocat     |           +---------+   :
    |  X60 +     |<--RS232-data-->| Chipflasher |---+3.3V-->| SPI     |   :
    |  Docking   |                |             |<---SPI--->|  Chip   |   :
    |            |----+-+5V-USB-->| firmware:   |           +---------+   :
    | software:  |   /            |  `kick'     |           :             :
    | `connect'  |--+             +-------------+           : Systemboard :
    |            |                                          : without     :
    +------------+                                          : Battery     :
                                                            : nor Power   :
                                                            +·············+

Power Supply

WARNING: Proceed on your own risk!

1. Discharge your body (touch any grounded metal like a water pipe) and make sure your are not electrostatically charged.

2. If you are flashing a sysboard:

   • Do not power the sysboard on, nor connect any power plug.
   • Remove the main battery.
   • Unplug the small coin-battery.

3. Power and GND will be applied to the SPI-chip by the chipflasher board only.

   Make sure you have not mixed these wires!
   See ../../hardware/gschem/chipflasher-page13.sch.png for pinouts.

4. To power the chipflasher:

   • You may safely use your computer’s USB port according to official specs if you are going to flash a single desoldered chip.

   • In case of flashing chips in situ, soldered onto sysboards, please use an external USB-Power-Adapter (5VDC @ 1.000mA).

   • As a workaround, you may try a non-standard Y-USB-Cable which should work well in many cases, as the maximal requested current per USB port typically won't exceed 500mA. See #../../doc/power-profiles.md to get into details.

Clock Quality

The Zerocat Chipflasher is a handmade tool with long wires/open case that may catch or generate electromagnetic interference. To give you an idea about clock pulse quality and speed, we probed the signals right at the test-clip for you. The maximal SPI clock speed should be above 2.5MHz.

Precautions

The software connect and the firmware kick are talking to each other via serial RS232 lines. Occasional transmission errors will be repaired automatically. However, if you encounter severe connection problems that render you helpless when trying to verify your data, boot the host with WLAN and network switched off, make sure that no other resource demanding process will start up (e.g. browser), and try again.

As long as the SPI-Bus Status LED (red) is not active, the SPI-Chip is not powered and you may feel free to connect/disconnect your target. However, if the LED is active, don't touch the connection!

If the system hangs for any reason, you should be save to kill the chipflasher’s power, because all SPI bus pins are configured to enter a harmless tristate mode right at brown-out or power-off. However, you might notice some flickering¹ of the SPI-Power LED, so better do not rely on that procedure.

¹ fixed with Chipflasher v2 design

Prerequisites

It is assumed that you have followed the steps mentioned in #../../doc/README.md and now have two terminal windows available, with proper environments set up, i.e. Terminal#1 and Terminal#2.

Get Prepared

Connect host and chipflasher with each other, i.e. attach the Y-USB-power-cable to two USB-Ports, attach the RS232-data-cable.

Attach the SPI-cable, but omit the target board (or chip) for now.

1. Switch the chipflasher device on and verify that the power status LED is bright.

2. Use a screwdriver to adjust the flasher’s CE# pull-up resistor to its clock-wise maximal position, that is to its biggest value.

3. Attach the free pinheader connectors of the SPI-cable to the SPI-Chip...

   • by using the 8-pin DIL-socket for discrete chips,
   • by using a test-clip for chips in place,
   • or by connecting previously soldered, flying wires.

   WARNING: You must not mix wires! See ../../hardware/gschem/chipflasher-page13.sch.png and check pinouts in advance.

Operate the Chipflasher

Change the directory to ease operation:

    [env]$ cd ../../host/start/

Get familiar with targets, provided by ../../host/start/Makefile:

    [env]$ make help

Get familiar with targets, provided by ../../host/start/Workflow.mk:

    [env]$ make -f Workflow.mk help

The flasher is operated via two terminal windows in parallel:

• Terminal#1 is used to start and operate the flasher via menu.

  In order to initiate the kick firmware upload into free-design RAM, and to start the connect utility, type:

      [env]$ make kick-v1-connect-115200-ram
      [env]$ make connect-115200
  

  The flasher’s menu should appear on screen:

  

  Screenshot: Start from RAM

• Terminal#2 is used to monitor in- and outgoing chip data.

  Learn about typical, standard workflows and type:

      [env]$ make -f Workflow.mk workflow-chip-read
      [env]$ make -f Workflow.mk workflow-chip-write
  

  Learn about typical workflows for targets with virtual 12MB chips:

      [env]$ make -f Workflow.mk workflow-virtual-chip-read
      [env]$ make -f Workflow.mk workflow-virtual-chip-write
  

Feel free to switch between terminals as required.

Try a Real Target

1. In Terminal#1, select d: probe chip in order to probe the BIOS-chip for its ID:

   

   Screenshot: Probe Chip

   Use a screwdriver in counter-clock-wise direction to adjust the CE# pull-up resistor to smaller values until your chip gets clearly detected. See #../../doc/targets.md.

2. Select ?: show menu to get a verbose menu output:

   

   Screenshot: Show Menu

3. Select c: read chip in order to store chip’s content in your first chip2file.txt.

   WARNING: Consider to create backups between read operations, as file chip2file.txt gets overwritten without prompt!

4. Switch to Terminal#2 in order to monitor and manipulate in- and outgoing chip data.

   • You can do so, manually (See #../../doc/data-transfer.md), or

   • use predefined targets of ../../host/start/Workflow.mk, for instance:

     Type

         [env]$ make -f Workflow.mk list
     

     to get existing I/O files listed.

5. Continue to Operate the Flasher via Menu (Terminal#1)

   You may now use the menu for dumping, erasing, flashing, verifying your chip. Check register bits for appropriate configurations.

   WARNING: Proceed with care, you may brick your machine!
   Potentially dangerous hotkeys are all upper case, thus protecting you from accidental key hits as long as <CAPS-LOCK> is inactive.

   When using the menu, wait until your selected procedure finishes.
   With q: cancel/(SPI-Bus off)/quit you may cancel it at any time.

6. When done, hit q in order to quit connect.

   NOTE: In case the SPI bus has been left powered after chip detection due to volatile bits in status registers, it is powered off as an intermediate step before you actually quit the program with an additional q.

7. Detach the SPI-cables from the target SPI-chip and power off the flasher device.

   Remember to plug a system board’s coin-battery back in.

Done!

Onboard EEPROM (Terminal#1)

Until now, we have taken care to always start from free-design RAM using the make -C ../../host/start/ kick-ram command. The pre-flashed firmware in the onboard EEPROM has not been touched, yet.

If you want to try the pre-flashed firmware, type:

    [env]$ make -C ../../host/start/ reset-kick
    [env]$ make -C ../../host/start/ connect-115200

If you want to upload a newly built firmware and make things permanent, type:

    [env]$ make -C ../../host/start/ kick-eeprom

Custom Invocation of connect (Terminal#1)

Alternatively, you might invoke the connect utility manually:

1. Adjust the port pointer, e.g.:

       [env]$ ln -sf /dev/ttyS1 ../../host/start/tty_port_pointer
   

2. Clean and compile connect, the utility:

       [env]$ make -C ../../host/src/ clean
       [env]$ make -C ../../host/src/ connect
   

3. Configure and compile kick, the firmware:

       [env]$ make -C ../../firmware1/src/ clean
       [env]$ make -C ../../firmware1/src/ config-BOARD_V1
       [env]$ make -C ../../firmware1/src/ kick
   

4. Adjust baudrate and upload kick to RAM:

       [env]$ make -C ../../firmware1/start/ config-baud57600
       [env]$ make -C ../../firmware1/start/ kick-ram
   

5. Invoke connect with matching parameters, i.e.:

       [env]$ ../../host/src/connect\
           ../../firmware1/start/chip-out.txt\
           ../../firmware1/start/chip-in.txt\
           ../../host/start/tty_port_pointer\
           B57600
   

6. In order to process in- and outgoing data via ../../host/start/Workflow.mk, update macros ROOT_HOST_IO, CHIP2FILE and FILE2CHIP according to your choices.

7. Clean-up your custom configuration:

       [env]$ make -C ../../firmware1/start/ clean-config